[HDX-3919] Add @hyperdx/cli package — terminal TUI, source map upload, and agent-friendly commands#2043
[HDX-3919] Add @hyperdx/cli package — terminal TUI, source map upload, and agent-friendly commands#2043kodiakhq[bot] merged 50 commits intomainfrom
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🦋 Changeset detectedLatest commit: 6cebd1e The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
E2E Test Results✅ All tests passed • 130 passed • 3 skipped • 1085s
Tests ran across 4 shards in parallel. |
PR Review
✅ Session file permissions ( |
🔴 Tier 4 — CriticalTouches auth, data models, config, tasks, OTel pipeline, ClickHouse, or CI/CD. Why this tier:
Additional context: large diff (6771 lines) Review process: Deep review from a domain expert. Synchronous walkthrough may be required. Stats
|
- Port upload-sourcemaps from hyperdx-js/packages/cli with modernizations: native fetch (Node 22+), ESM-compatible version string, proper types - Add query command for raw SQL execution against a source's ClickHouse connection, with --format support and LLM-friendly --help - Remove stream command (superseded by query + tui) - Add glob@^13.0.6 dependency for source map file discovery Ref: HDX-3920
- Add dashboards command listing all dashboards with tile summaries, supports --json with simplified tile metadata for agent consumption - Add query command for raw SQL execution against a source's ClickHouse connection, with --format support and LLM-friendly --help - Remove stream command (superseded by query + tui)
- Remove dead code: formatEventRow, formatTraceRow, getSeverityColor, getSpanEventBody (replaced by formatDynamicRow) - Remove unused re-export of ROW_DATA_ALIASES from eventQuery.ts - Un-export internal-only symbols: INTERNAL_ROW_FIELDS, processRowToWhereClause, buildAliasWith, _origDebug, _origWarn - Un-export internal-only interfaces: ApiClientOptions, MeResponse, ConnectionResponse, DashboardTileConfig, DashboardTile, DashboardFilter, DashboardResponse
…mands - Add release-cli job: builds npm package + standalone binaries, publishes to npm as @hyperdx/cli, creates GitHub Release with all 3 binaries - Remove private:true from package.json to enable npm publish - Remove Homebrew formula and related workflow steps - Update README with all current commands: tui, query, sources, dashboards, upload-sourcemaps, auth (login/logout/status) - Add upload-sourcemaps docs with v2 API version note - Add npm + npx + standalone binary installation instructions
…arate - npm publish now handled by changesets in check_changesets job (same flow as other packages in the monorepo) - Add publishConfig.access: public to CLI package.json - Add prepublishOnly: yarn build to ensure tsup bundles before publish - Remove manual npm publish step from release-cli job - release-cli job now only compiles standalone binaries + GitHub Release
- Remove skipNodeModulesBundle, add noExternal: [/.*/] to bundle all dependencies (ink, react, commander, @hyperdx/common-utils, etc.) - Keep Node.js built-ins external via module.builtinModules - Add createRequire banner shim so CJS deps (signal-exit, etc.) can use require() for Node built-ins inside the ESM bundle - dist/cli.js is now ~8MB self-contained, no node_modules needed - Bun binary compilation (yarn compile:*) unaffected
- Fix absolute path handling: use path.resolve() instead of path.join(cwd(), path) which double-joined absolute paths - Fix URL construction: use URL constructor instead of path.join() which stripped protocol slashes from URLs - Read PKG_VERSION from package.json instead of hardcoding
Remove query, sources, and dashboards docs from public README. Clarify that -s flag takes the HyperDX API URL. Add Ctrl+D/U and other missing keybindings to the table.
Check response.ok before parsing JSON to avoid SyntaxError on 'Forbidden' or other non-JSON error responses. Show clear error message: 'Authentication failed (403). Check your --serviceKey and --apiUrl.'
console.error/log/info are silenced by silenceLogs.ts for TUI mode, which hid all error messages from upload-sourcemaps. Use direct process.stdout/stderr.write so errors are always visible. Also include the response body in the 'Unable to generate upload URLs' error for debugging.
- Retry failed uploads up to 3 times with 1s/3s exponential backoff - Only retry on network errors and 5xx; no retry on 4xx (permanent) - Show [1/177] progress prefix on every upload message - Print summary at end: X succeeded, Y failed out of Z files - Individual failures don't crash the batch (all files get attempted)
- Pin softprops/action-gh-release@v2 to full commit SHA (v2.2.1) to mitigate supply chain risk with GITHUB_TOKEN write access - Pin bun-version to 1.3.11 in CI workflow for reproducible builds - Add bun engine constraint to packages/cli/package.json
Add a check step that queries gh release view before compiling
binaries. If cli-v{version} already exists, the compile and
release steps are skipped — prevents failures on repeated Docker
releases that don't bump the CLI version.
tsup bundles everything (noExternal: [/.*/]) into a single dist/cli.js, so runtime dependencies are not needed at install time. This reduces the npm install footprint for consumers.
Summary
Adds
packages/cli(@hyperdx/cli) — a unified CLI for HyperDX that provides an interactive TUI for searching/tailing logs and traces, source map upload (migrated fromhyperdx-js), and agent-friendly commands for programmatic access.Ref: HDX-3919
Ref: HDX-3920
Ref: HDX-3927
CLI Commands
Key Features
Interactive TUI (
hdx tui)/for Lucene search,sto edit SELECT clause in$EDITOR,tto edit time rangewto toggle line wrapDetail Panel (3 tabs, full-screen with Ctrl+D/U scrolling)
SELECT *row data with__hdx_*aliased columnsDBTraceWaterfallChartDAG builder) with correlated log events, j/k span navigation, inverse highlight, Event Details sectionAgent-friendly commands
hdx sources --json— Full source metadata with ClickHouseCREATE TABLEDDL, expression mappings, and correlated source IDs. Detailed--helpdescribes the JSON schema for LLM consumption. Schema queries run in parallel.hdx dashboards --json— Dashboard metadata with simplified tile summaries (name, type, source, sql). Resolves source names for human-readable output.hdx query --source <name> --sql <query>— Raw SQL execution against any source's ClickHouse connection. Supports--formatfor ClickHouse output formats (JSON, JSONEachRow, CSV, etc.).Source map upload (
hdx upload-sourcemaps)hyperdx-js/packages/clito consolidate on a single@hyperdx/clipackage-k/HYPERDX_SERVICE_KEYenv var).jsand.js.mapfiles, handles Next.js route groupsfetch(Node 22+), ESM-compatible, proper TypeScript typesArchitecture
Tech Stack
/clickhouse-proxy)renderChartConfig,chSqlToAliasMap)noExternal: [/.*/], zero runtime deps)~/.config/hyperdx/cli/session.jsonCI/CD (
release.yml)cli-v{version}tag already existssoftprops/action-gh-releasepinned to full SHA (v2.6.1) for supply chain safety1.3.11for reproducible buildsKeybindings
j/kl/Enterh/EscG/gCtrl+D/U/Tabstfw?Demo
Main Search View
Event Details Overview
Trace Waterfall